Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 181-188: The example in README.md uses an invalid script type
causing the block to be inert; update the <script> tag around the
createContextWith(...) example to either omit the type attribute or use a valid
MIME type such as "text/javascript" (or "application/javascript") so the
JavaScript that calls sdk.createContextWith(...) will execute in the browser.

In `@scripts/generate-version.ts`:
- Around line 3-4: Guard the package.json version before writing src/version.ts:
check that the parsed pkg.version exists and is a string (e.g., validate
pkg.version !== undefined && typeof pkg.version === "string") in the
generate-version script, and if the check fails, print a clear error and exit
non‑zero instead of calling writeFileSync; when valid, write the SDK_VERSION as
before. Ensure you reference pkg.version, the writeFileSync call that writes
`export const SDK_VERSION = ...`, and fail fast with a descriptive message to
avoid emitting an invalid constant.

In `@src/__tests__/client.test.ts`:
- Around line 90-96: Several test suites stub the global fetch via
vi.stubGlobal("fetch", vi.fn()) in their beforeEach hooks but only call
vi.restoreAllMocks() in afterEach; add vi.unstubAllGlobals() to each afterEach
that pairs with a vi.stubGlobal call (the afterEach blocks adjacent to the
beforeEach that stubs fetch — look for the vi.stubGlobal("fetch", vi.fn()) calls
in src/__tests__/client.test.ts) so globals are removed between tests; ensure
you call vi.unstubAllGlobals() after vi.restoreAllMocks() in each affected
afterEach (the blocks around lines shown in the review: the afterEach following
the beforeEach that stubs fetch at ~lines 90–96, 125–131, and 174–182).

In `@src/__tests__/errors.test.ts`:
- Around line 61-66: Update the "has correct name and default message" test for
AbortError to actually assert the default message: after creating const error =
new AbortError(); add an assertion that checks error.message equals the
AbortError default (e.g., expect(error.message).toBe(AbortError.DEFAULT_MESSAGE)
or, if there is no static constant, assert the known default string used by the
class, or at minimum expect(typeof error.message).toBe("string") and
expect(error.message.length).toBeGreaterThan(0); this ensures the default
message is verified alongside the existing checks for instance and name.

In `@src/__tests__/sdk.test.ts`:
- Around line 54-62: The test stubs the global fetch via vi.stubGlobal(...) but
only calls vi.restoreAllMocks(), so the global stub remains; update the test to
call vi.unstubAllGlobals() after restoring mocks (or instead of) to fully remove
the global stub — locate the SDK instantiation and context creation in the test
(SDK, createContext) and add a vi.unstubAllGlobals() call (e.g., after
vi.restoreAllMocks() or replace it) to properly clean up the global fetch stub.

In `@src/hashing.ts`:
- Around line 7-13: The surrogate-handling logic allows lone UTF-16 surrogates
to be encoded directly; update the blocks that inspect c, next, i and
value.charCodeAt(...) so that any unpaired high surrogate (0xD800–0xDBFF with no
valid following low surrogate) or any lone low surrogate (0xDC00–0xDFFF) is
replaced with the Unicode replacement code point 0xFFFD before proceeding to
UTF-8 byte emission; specifically, in the branch that currently computes a
paired surrogate (where you set c = ((c - 0xd800) << 10) + (next - 0xdc00) +
0x10000 and increment i), keep that for valid pairs, but when the next char is
absent or not in 0xDC00–0xDFFF set c = 0xFFFD (and do not increment i), and in
the other branch that sees a low surrogate alone also set c = 0xFFFD — ensure
these changes are applied to the same surrogate-checking sections so subsequent
UTF-8 encoding uses 0xFFFD for lone surrogates.

In `@src/interfaces.ts`:
- Around line 15-17: ContextParams currently only exposes units, but the
codebase supports initial attributes via the Attribute interface and
PublishParams; add an optional attributes?: Attribute[] to the ContextParams
type so callers can supply initial attributes on creation, update any
constructors or factory functions that accept ContextParams (e.g., context
creation methods) to read and apply params.attributes when present, and ensure
typings referencing ContextParams (and any usage in PublishParams flows) accept
and propagate the new optional field.

In `@src/jsonexpr/operators.ts`:
- Around line 31-37: The OrCombinator.evaluate implementation currently treats
an empty args array as truthy by returning args.length === 0; change this so
that an empty disjunction returns false instead. Locate the
OrCombinator.evaluate method in src/jsonexpr/operators.ts and replace the final
return that checks args.length with a straight false (so { or: [] } evaluates to
false) while keeping the existing loop and
evaluator.booleanConvert(evaluator.evaluate(expr)) logic intact.

In `@src/sdk.ts`:
- Around line 139-150: The _validateParams method currently assumes params.units
exists and iterates it, causing a TypeError when callers like createContext or
createContextWith pass no units; update _validateParams to explicitly handle a
missing or falsy params.units (e.g., treat undefined/null as an empty object or
return early) before the for-loop so validation only runs when units is present,
keeping the existing checks for type and empty strings intact and referencing
_validateParams, createContext, and createContextWith to locate the related call
sites.
- Around line 60-72: The constructor currently typed as constructor(options:
ClientOptions & SDKOptions) forces required ClientOptions even when
options.client is provided; change the signature to a union that allows
providing a custom client without supplying DefaultClient fields, e.g.
constructor(options: (ClientOptions & SDKOptions) | (Partial<ClientOptions> &
SDKOptions & { client: ClientInterface })), leaving the internal logic using
options.client and new DefaultClient(clientOptions) unchanged; update any
related type imports (ClientOptions, SDKOptions, ClientInterface) and ensure
this._client assignment code still compiles against the new union type.

---

Outside diff comments:
In `@src/config.ts`:
- Around line 45-66: The code only handles existing path segments but skips
creating missing intermediate objects; update the traversal in the block around
target/frag/frags/index so that when index < frags.length - 1 and frag is not
present on target you create target[frag] = {} (then set target = target[frag]
as Record<string, unknown>), while keeping the existing branch that warns and
replaces non-objects; leave the Object.defineProperty logic for the final
segment (using experimentName, context.variableValue(variableKey, defaultValue),
and the _{frag}_setter) unchanged.

In `@src/context.ts`:
- Around line 857-887: The publish snapshot code can race with finalize():
record the in-flight publish as a property (e.g., this._inFlightFlush or
this._isFlushing + this._inFlightFlushPromise) when you call
this._publisher.publish(request,...), set it before awaiting/then/catch, and
clear it in both the then and catch handlers; update the catch to still restore
pendingCount/pendingExposures/pendingGoals as it does now. Modify finalize() (or
_finalize()) to await this in-flight flush promise (or check the _isFlushing
flag) before sealing the context so a concurrent publish failure can restore
events and be retried. Ensure the new property is initialized on the context
class and cleared in all publish completion paths.

In `@src/md5.ts`:
- Around line 152-153: The padding sets only the low 32-bit word (block[14] = l
<< 3) so very large payloads lose the high 32 bits of the bit-length; update the
padding to assign both block[14] and block[15] so the full 64-bit bit-length is
passed into md5cycle — compute the low 32 bits as (l << 3) and the high 32 bits
from the upper bits (e.g., combine (l >>> 29) with h << 3 or equivalent using
the existing length high variable) and set block[15] accordingly before calling
md5cycle(state, block).

---

Nitpick comments:
In `@package.json`:
- Around line 49-55: Update package.json devDependencies to use pinned exact
versions instead of caret ranges: replace entries under the "devDependencies"
object (tsup, typescript, vitest, tsx, `@vitest/coverage-v8`) to fixed version
strings (e.g., "tsup": "8.0.0") to ensure reproducible builds; make the change
where the "devDependencies" key and those package names are defined so CI and
local installs always pull the exact same versions.

In `@src/__tests__/md5.test.ts`:
- Around line 4-44: The stringToBuffer helper does not handle UTF-16 surrogate
pairs (non-BMP characters) and will misencode code points above 0xFFFF; update
stringToBuffer to iterate by Unicode code points (using codePointAt and
advancing i by 1 or 2 appropriately) or use TextEncoder to produce a UTF-8
ArrayBuffer, ensuring md5 tests feed correct UTF-8 bytes; locate and change the
stringToBuffer function and keep toHex and the test cases unchanged.

In `@src/__tests__/provider.test.ts`:
- Around line 12-13: Add an assertion that mockGetContext was invoked exactly
once to prevent accidental duplicate calls; update the test in provider.test.ts
to include expect(mockGetContext).toHaveBeenCalledTimes(1) alongside the
existing expect(mockGetContext).toHaveBeenCalledWith({ path: "/test" }) and
expect(result).toEqual({ experiments: [] }) so the test verifies both the call
arguments and the single invocation of getContext (mockGetContext).

In `@src/client.ts`:
- Around line 119-125: The null check on the text from response.text() is
redundant; update the error construction inside the response.text().then(...)
callback (the block that creates const error: Error & { _bail?: boolean }) to
test for empty string only (e.g., use text.length > 0 or text !== "" to select
text, otherwise use response.statusText), then set error._bail = bail and reject
as before.
- Around line 152-158: The code is losing the original error stack by creating
new Error instances in the catch of tryOnce; update the bail and timeout/error
branches to preserve the original error as the cause (or rethrow the original
error) instead of throwing plain new Error(reason.message). Specifically, in the
catch handling inside tryOnce's promise you should: for the bail case use throw
new Error("bail: ...", { cause: reason }) or rethrow reason; for the
timeout/AbortError branch ensure you throw TimeoutError or the original reason
with cause preserved (TimeoutError should include the original reason as its
cause if appropriate). Keep references to reason, retries, tries, RetryError,
TimeoutError and tryWith.timedout when making these changes so the original
stack is preserved.

In `@src/errors.ts`:
- Around line 1-20: Change the SDK error hierarchy so all specific errors extend
ABSmartlyError instead of Error: update TimeoutError, RetryError, AbortError
(and any other plain Error subclasses) to subclass ABSmartlyError, ensure their
constructors call super(message) and set this.name (e.g., "TimeoutError",
"RetryError", "AbortError"); keep existing ABSmartlyError, ContextNotReadyError,
and ContextFinalizedError behavior but ensure their prototypes align with
ABSmartlyError so consumers can use instanceof ABSmartlyError for unified error
handling.

In `@src/index.ts`:
- Around line 35-47: The public API currently re-exports types from
"./interfaces" but does not export the DefaultClient class, preventing advanced
users from instantiating or extending it; add an export for DefaultClient from
"./client" (e.g., export { DefaultClient } from "./client") so consumers can
directly import DefaultClient while leaving existing SDKOptions.client injection
unchanged and reference DefaultClient in documentation/examples; locate the
existing export block in this file to add the new export alongside the type
exports.

In `@src/interfaces.ts`:
- Around line 67-74: The ContextPublisher.publish signature currently types the
context parameter as unknown; change it to a more specific type (e.g., Context
or a minimal interface like PublishContext) to improve type safety: update the
publish method signature in the ContextPublisher interface to use that concrete
type for the context parameter, import or declare the Context/PublishContext
type in this file, and then update all implementations of
ContextPublisher.publish to accept and use the new typed context (adjust any
call sites or tests accordingly).

In `@src/jsonexpr/evaluator.ts`:
- Around line 178-181: The boolean branch in the evaluator uses a loose
inequality when checking rvalue from this.booleanConvert(rhs); update the case
"boolean" logic to either use strict comparison (rvalue !== null) or, better,
remove the null check entirely since booleanConvert always returns a boolean;
directly compute and return lhs === rvalue ? 0 : lhs > rvalue ? 1 : -1 in the
case "boolean" block (identify and modify the code around this.booleanConvert
and the local rvalue variable).

In `@src/utils.ts`:
- Around line 107-109: The function arrayEqualsShallow uses a compact
short-circuit: it returns true if both references are identical, otherwise it
checks equal lengths and that no element differs via a?.some((va,vi)=> b && va
!== b[vi]); add a brief clarifying comment above arrayEqualsShallow that
explains these steps (reference identity check, length equality, shallow
strict-equality element comparison) and calls out the optional chaining/guard on
b to avoid null access so readers understand the intent and safety.